home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 8 / The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO / prg_gen / swag.zip / SWAGADD.DOC < prev    next >
Text File  |  1996-11-29  |  10KB  |  227 lines
  1.  
  2.  
  3.                              SWAGADD.EXE v1.0
  4.                             (SWAG snipet ADDER)
  5.                                 (c) GDSOFT
  6.                                  May 1995
  7.  
  8. INTRODUCTION
  9. ------------
  10.  
  11. Since the  inception of SWAG over  two years ago, it  has become a standard
  12. library used by PASCAL programmers all over the world. I often receive mail
  13. from  users  wanting  to  create  their  own  SWAG  packets. Therefore, I'm
  14. releasing SWAGADD which is the program that I use to create the new snipets
  15. every 90 days.
  16.  
  17. SWAG  (.SWG) files  are actually  highly compressed  LZH archive files with
  18. extensions to the header and a double splayed sliding dictionary compressed
  19. buffer.
  20.  
  21. The SWAG file headers have this structure :
  22.  
  23. TYPE
  24.   SwagHeader =
  25.     RECORD
  26.       HeadSize : BYTE;                  {size of header}
  27.       HeadChk  : BYTE;                  {checksum for header}
  28.       HeadID   : ARRAY [1..5] OF CHAR;  {compression type tag}
  29.       NewSize  : LONGINT;               {compressed size}
  30.       OrigSize : LONGINT;               {original size}
  31.       Time     : WORD;                  {packed time}
  32.       Date     : WORD;                  {packed date}
  33.       Attr     : WORD;                  {file attributes and flags}
  34.       BufCRC   : LONGINT;               {32-CRC of the Buffer }
  35.       Swag     : STRING[12];            {stored SWAG filename}
  36.       Subject  : STRING[40];            {snipet subject}
  37.       Contrib  : STRING[35];            {contributor}
  38.       Keys     : STRING[70];            {search keys, comma deliminated}
  39.       FName    : PathStr;               {filename (variable length)}
  40.       CRC      : WORD;                  {16-bit CRC (immediately follows FName)}
  41.     END;
  42.  
  43. Following each header is a highly compressed buffer optimized for space and
  44. extraction speed. This makes the extraction or viewing of snipets VERY VERY
  45. FAST.  Unfortunately, you  WILL NOT  be able  to use  standard LZH  code to
  46. decompress this buffer, however, you'll  find code in the SWAG distribution
  47. to read the headers. Maybe someday,  I'll release the decompression code to
  48. the public domain, but for now, it's copyrighted, and unavailable.
  49.  
  50. GETTING STARTED
  51. ----------------
  52.  
  53. The program SWAGADD.EXE is a executable program that will allow you to read
  54. a directory of  files and add them  selectively to .SWG files  somewhere on
  55. your disk.  Any files can be  added to any .SWG  file. The only limitations
  56. are  that the  file  must  be an  ASCII file  and less   than 64K  is size.
  57.  
  58. Actually, you could save ANY thing in a SWAG file. Recipes, Assembler code,
  59. "C" code or any type of ASCII files. I have a friend who keeps his favorite
  60. recipes in  .SWG format. You  wil find that  you'll get compression  ratios
  61. almost as  good as PKWARES  PKZIP. The  main  feature is that  once data is
  62. added, you'll find that the extraction ratio is MUCH faster than PKZIP.
  63.  
  64. USING SWAGADD
  65. -------------
  66.  
  67. Using the program  is really very simple. Just execute  it, and you will be
  68. presented with a  directory of all of the .files  in the directory that you
  69. started from.  You'll be able  to navigate by  simply selecting one  of the
  70. directory entries  instead of one of  the actual files. You'll  notice that
  71. some files  in the directory  will NOT be  listed; EXE, COM,  ZIP, ARJ, LZH
  72. etc. Use the HOME, END and the arrow keys to maneuver around.
  73.  
  74. ALSO,
  75.  
  76. The  directory window  is search  key sensitive.  This means that directory
  77. box, you can just type the name of the file you want. For example, pressing
  78. 'A' will place you at the first entry starting with 'A'. Press 'N', and you
  79. will jump the the entry with 'AN...' if you have one. If NOT, you will jump
  80. the first file starting with the letter 'N'.
  81.  
  82. At the bottom  of the screen you will notice  a menu indicating some cursor
  83. and function keys :
  84.  
  85.                         F1   - HELP
  86.                         F3   - OPTIONS
  87.                         AltM - Mask
  88.                         <ENTER> - Read
  89.                         ESC - QUIT
  90.  
  91. F1 shows  you a little help  screen for both the  file selection window and
  92. the snipet window.
  93.  
  94. F3 let's you set some options that are available.
  95.  
  96. AltM permits you to enter a specific path and mask.
  97.  
  98. <ENTER> opens  up the snipet  window, and all  for some additional  command
  99. keys:
  100.  
  101. ALT[N],
  102. CTRL[ENTER] - View the NEXT snipet
  103.  
  104. ALT[V] - View PREVIOUS snipet
  105.  
  106. ALT[S] - Save Snipet
  107.  
  108. This is the main function of SWAGADD.  You'll be able to enter the subject,
  109. from, and keys that you want included in the packet. You'll be prompted for
  110. the .SWG file where you want to put  the snipet, and also you will be given
  111. the opportunity to enter the packet description. If the .SWG files does not
  112. already exist, it will be created.
  113.  
  114.         AUTOMATIC HEADERS
  115.         -----------------
  116.  
  117.         You can include the following on the FIRST line of you snipet file,
  118.  
  119.                          {SWAG=SWAGFNAME,FROM,SUBJECT,KEYS}
  120.  
  121.         SWAGADD  will parse  this string   if found,  and default  the SWAG
  122.         filename, from, subject and keys  for you automatically. This makes
  123.         adding a directory of files very easy and fast.
  124.  
  125.  
  126. ALT[F] - SWAG File
  127. ------------------
  128.  
  129. Allows you enter the SWAG files that the snipet will be included in.
  130.  
  131. ALT[C] - Check for Duplicate
  132. ----------------------------
  133.  
  134. This activates  a function that attempts  to insure that this  snipet is an
  135. original. EVERY snipet in every .SWG files is checked against the snipet to
  136. be added  for duplication. The  technique is not  fool-proof, and used  two
  137. methods to do the analysis. First,  every PROCEDURE and FUNCTION is checked
  138. to a  percentage of matches. Greater  than 50% indicates a  possible match.
  139. Next, the  entire text is  checked line by  line. If we  get 66% or  better
  140. matches, then  we can assume that  we probably have a  duplicate snipet. At
  141. least it is very very close.
  142.  
  143. As the process runs, you'll notice at the bottom of the screen :
  144.  
  145.  
  146.         SOMEFILE.PAS in ANSI.SWG    0009 01/01 11/68 16%
  147.              ^           ^           ^    ^     ^     ^
  148.         File Name       SWAG File    No. Procs Text  Pct
  149.  
  150. This shows  the possible "finds"  as it checks  each snipet. If  the screen
  151. turns dark blue, then you probably have  a duplicate, and a box will pop on
  152. the screen and allow to mark the file, view the snipet involved or skip and
  153. proceed. You'll have to make the decision  as to whether you want to add it
  154. or not.
  155.  
  156. ALT[G] - GREP
  157. -------------
  158. The GREP function is another tool designed to help you decide if you have a
  159. duplicate snipet or not.
  160.  
  161. Enter a string  to search for. You may search  for a multiple occurrence of
  162. substrings using  BOOLEAN operators AND (&)  OR (|). For example,  a search
  163. for  THIS&THAT|THEM&THOSE would  return  all  snipets containing  both ORed
  164. phrases THIS&THAT OR THEM&THOSE.
  165.  
  166. In BOOLEAN Algebra, the AND operator  takes precedence over the OR operator
  167. (except  when  using  parentheses).  This  is  NOT  the  case with the GREP
  168. function. You  can use the PARENTHESES  () to dictate which  portion of the
  169. search string is  to be processed first. If  multiple levels of parentheses
  170. are used,  the order is RIGHT  to LEFT, starting with  the innermost set of
  171. parentheses, wherever they occur.
  172.  
  173. As an example, in the phrase ((this|that)&(them&those)), (them&those) would
  174. be processed  before (this|that)) innermost  to outermost. In  other words,
  175. all snipets  will be returned  containing THIS or  THAT AND they  also will
  176. contain (THEM and THOSE).
  177.  
  178. Within a set  of parentheses, order will be left  to right. Construction of
  179. the search string itself requires combining the desired substrings together
  180. with  the desired  BOOLEAN operators.  Without the  parentheses, the search
  181. string will be processed logically. THIS|THAT&THEM&THOSE will return all of
  182. the snipets  that contain THIS  plus the  ones  that contain THAT  & THEM &
  183. THOSE. You can  see that this is totally different  than what you'll get by
  184. using the parentheses.
  185.  
  186. The  program will  search ALL  of the  SWAG packet  HEADERS in  the CURRENT
  187. directory for matches based on your criteria. A processing box will appear,
  188. and  all occurrences  of your  search  string(s)  or date  matches will  be
  189. written to a NEW SWAG file. Initially, this file is named GREPSWAG.SWG, and
  190. will be in the current directory. Upon completion of this GREP process, you
  191. will be asked  for the file name. Enter any  name AND directory you choose,
  192. and the file  will be RENAMED and moved to  that directory. Pressing ESCAPE
  193. WILL NOT save a  file at all. This process allows you  to create SWAG files
  194. containing ANY combination of material that you please.
  195.  
  196. You can  ALSO search the ENTIRE  SWAG snipet buffer for  data. Just enter a
  197. tilde (~) character as the FIRST character on the search line. For instance
  198. to  find all  snipets containing  CRT, you  would enter  ~CRT on the search
  199. line. ONLY  the header of snipets  is searched for matches.  This a way you
  200. can look at all snipets by a certain contributor. You can also use multiple
  201. search criteria  here. For instance,  ~GAYLE DAVIS|GUY MCLOUGHLIN|JOE  BLOW
  202. would bring back  everything for each of these  persons. This search method
  203. is VERY fast as on the headers have  to be read. By the way, the same rules
  204. about AND/OR searching apply when search just the headers.
  205.  
  206.  
  207. THE SWAG ENVIRONMENT VARIABLE
  208. -----------------------------
  209.  
  210. Some users reported a considerable delay while SWAG programs looked for the
  211. .SWG files on  their disks. This problem has been  eliminated by adding the
  212. environment variable SWAG to allow total override of the SWAGDIR= switch in
  213. the READER.INI. Use the command :
  214.  
  215.                         SET SWAG=yourpath
  216.  
  217. at the DOS prompt to set this.  This then become the ABSOLUTE location that
  218. READER and other  programs use to as the beginning  path for SWAG files and
  219. WILL OVERRIDE you setting in the READER.INI file.
  220.  
  221. We  hope that  you find  this program  easy to  use, and  the SWAG material
  222. valuable in development of your PASCAL programs.
  223.  
  224. ENJOY !!!!! and GOOD PROGRAMMING !!!
  225.  
  226. Gayle Davis
  227.